home *** CD-ROM | disk | FTP | other *** search
/ Aminet 8 / Aminet 8 (1995)(GTI - Schatztruhe)[!][Oct 1995].iso / Aminet / text / tex / bibcard_091.lha / BibCard / BibCard.doc < prev    next >
Text File  |  1995-08-27  |  17KB  |  619 lines
  1.  
  2.                     *********************************
  3.                     *                               *
  4.                     *          BibCard v0.91        *
  5.                     *                               *
  6.                     *    (c) 1995 Matthijs Luger    *
  7.                     *                               *
  8.                     *********************************
  9.  
  10.  
  11. The programs and files in this distribution are freely distributable, but
  12. are also copyright (c) Matthijs Luger. They may be freely distributed as
  13. long as no more than a nominal fee is charged to cover time and copying
  14. costs.
  15.  
  16. No commercial usage is permitted without written permission from the
  17. author. Everything in this distribution must be kept together, in original
  18. unmodified form.
  19.  
  20. The above is generally known as freeware.
  21.  
  22. If you have suggestions or remarks about this program, or if you find any
  23. bugs, please let me know.
  24.  
  25.    Contacting the author:
  26.  
  27.      Internet: mluger@bio.vu.nl
  28.  
  29.      Fido:     2:280/509.4 (Matthijs Luger)
  30.  
  31.      Mail:     Matthijs Luger
  32.                J. Bernardusstraat 7-2
  33.                1091 TR Amsterdam
  34.                Netherlands
  35.  
  36.  
  37. """"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
  38.  
  39. Contents
  40. ========
  41.  
  42.     1. Introduction
  43.  
  44.     2. Usage
  45.  
  46.     3. Help
  47.  
  48.     4. Future
  49.  
  50.     5. Acknowledgments
  51.  
  52.     6. History
  53.  
  54.  
  55. """"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
  56.  
  57.  
  58. 1. Introduction
  59. ===============
  60.  
  61.  
  62.  ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! !
  63.  !                                                                       !
  64.  !  First I want to say that this program is not finnished yet, and that !
  65.  !  I'm still working at it. So it is possible to give comments and      !
  66.  !  suggestions for the next release.                                    !
  67.  !                                                                       !
  68.  !  I have tested it well before releasing this and I hope that there    !
  69.  !  are no nasty bugs in it, but be warned. Keep a copy of your valuable !
  70.  !  datafiles.                                                           !
  71.  !                                                                       !
  72.  ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! !
  73.  
  74.  
  75. BibCard is a database program to control BibTeX files. These are files
  76. with references to articles, books, conferences etc. and are used in
  77. combination with LaTeX.
  78.  
  79.  
  80. It requires minimal v2.04 (kickstart V37) of the operating system. It has
  81. been written and tested (using Mungwall and Enforcer) under v3.1 (V40),
  82. but should run under 2.04 and higher.
  83.  
  84. For selecting a screen mode V38 of the asl.library must be present.
  85.  
  86. BibCard has the following features:
  87.  
  88.   - It can handle multiple bib files at once. It opens for
  89.     every bib file a new window.
  90.  
  91.   - It has an extended Annotation option.
  92.  
  93.   - It has a @preamble option
  94.  
  95.   - It supports @string entries.
  96.  
  97.   - Every entry that is unknown for BibCard will be stored, 
  98.     saved and is also editable.
  99.  
  100.   - For every entry and field is some help, explaining where it is used for.
  101.  
  102.   - It can read "" and {} pair's for field delimiters.
  103.  
  104.   - Sensitive help.
  105.  
  106.   - Search option.
  107.  
  108.   - Supports text entering through the textfield.gadget.
  109.  
  110.   - BibCard opens on the Workbench, a public screen or it's own public screen.
  111.  
  112.   - For a custom screen any font can be choosen.
  113.  
  114.   - Is font sensitive.
  115.  
  116.   - Is an AppWindow.
  117.  
  118.   - Supports icon creation for saved bibfiles.
  119.  
  120.   - You name it, I make it...
  121.  
  122.  
  123.  
  124. BibCard supports now the textfield gadget for text entering. The suplied
  125. install script copies the textfield.gadget to SYS:Classes/Gadgets for
  126. kickstart V39 and above. For versions V37 and V38 it should be installed
  127. in a directory Gadgets in the same directory where BibCard is found.
  128.  
  129.  
  130. """"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
  131.  
  132.  
  133. 2. Usage
  134. ========
  135.  
  136. BibCard can be started from the Workbench or the Shell. Both methods give
  137. you some options. BibCard uses first its internal configuration, second
  138. the options set in the preferences file, and third any options given on
  139. the command line or as a tool type. An option set at the command line, or
  140. as tool type overides any thing set in the preferences file.
  141.  
  142.  
  143. The template is:
  144.  
  145.     FILE,DEFSCREEN=DEF/S,CUSTSCREEN=SCR/S,PUBSCREEN=PUB/K
  146.  
  147. Or more readable:
  148.  
  149.     BibCard [file] [def | scr | pub <name>]
  150.  
  151.         FILE              - Name of bib file.
  152.  
  153.         DEF or DEFSCREEN  - Switch to select the default public screen.
  154.  
  155.         SCR or CUSTSCREEN - Switch to select a custom screen.
  156.  
  157.         PUB or PUBSCREEN  - Name of the public screen to open on.
  158.  
  159.  
  160.  
  161. The ToolTypes are:
  162.  
  163.         FILE=<file>  - Name of bib file.
  164.  
  165.         SCREEN=<def|scr|pub<=name>>
  166.  
  167.                  def - Select the default public screen.
  168.  
  169.                  scr - Select a custom screen.
  170.  
  171.                  pub - Name of the public screen to open on.
  172.  
  173.  
  174.  
  175. The screen option need some more explaining. To open BibCard on a public
  176. screen set the ToolType according to this:
  177.  
  178.         SCREEN=pub=PubScreenName
  179.         
  180. Where PubScreenName is the name of the publc screen.
  181.  
  182.  
  183.  
  184.  
  185. The usage of BibCard is simple and need not much to explain. The menu's
  186. are self explaining.
  187.  
  188. There are six menu's which are explained below.
  189.  
  190.   Project
  191.   -------
  192.  
  193.     New         - Opens a new bibcard window.
  194.     Open        - Load a bib file.
  195.     Save        - Save a bib file.
  196.     Save As     - Save a bib file specifying a new name.
  197.     Merge       - Combines two bib files.
  198.     Preferences - To set some preferences.
  199.     About       - Tells it all.
  200.     Quit        - Quit BibCard.
  201.  
  202.  
  203.  
  204.   Edit
  205.   ----
  206.  
  207.     Add            - Add a new bib item at the end of the list.
  208.     Duplicate      - Duplicate the current item without the Cite Key.
  209.     Delete         - Delete the current item.
  210.     Annotation     - Edit the annotation for the current item.
  211.     Preamble       - Edit the preamble for the current file.
  212.     Abbrevations   - Edit the Abbrevations for the current file
  213.     Unknown Fields - Edit unknown fields for the current item.
  214.     Cut            - Removes the current item and store's it in its
  215.                      internal buffer.
  216.     Copy           - Copy the current item to the internal buffer.
  217.     Paste          - Inserts the internal buffer after the current item.
  218.  
  219.  
  220.  
  221.   Entry
  222.   -----
  223.  
  224.     Here you can select the entry type for the current item.
  225.  
  226.  
  227.   View
  228.   ----
  229.  
  230.     Next   - Next item.
  231.     Prev   - Previous item.
  232.     First  - First item.
  233.     Last   - Last item.
  234.  
  235.  
  236.   Cite
  237.   ----
  238.  
  239.     List Cites - Show a ListView with all the Cite Keys.
  240.  
  241.  
  242.   Find
  243.   ----
  244.  
  245.     Find      - Find an item witch matches some criteria.
  246.     Find Next - Find the next item that matches the above.
  247.     Find Prev - Find the previous item that matches the above.
  248.  
  249.  
  250.  
  251. Saving and Loading
  252. ------------------
  253.  
  254. Every new opened BibWindow has a default name `bibcard-<n>.bib' where <n>
  255. is a number. When you select <Save> that name will be used to store the
  256. bibfile. There will be NO WARNING if that file already exist so the file
  257. will be overwritten.
  258.  
  259. If the CiteKey field is empty you will be notified about it. It is not
  260. possible to save a bib file with empty CiteKeys.
  261.  
  262. When using Merge, the loaded bib file will be appended to the one in
  263. memory. Duplicated CiteKeys will be loaded.
  264.  
  265.  
  266. BibCard also supports the creation of an icon when a bibfile is saved.
  267. This option can be selected in the Preference Window.
  268.  
  269.  
  270.  
  271. Main Window and fields
  272. ----------------------
  273.  
  274. The window adapts itself to the number of fields for the different
  275. entries, and it will grow or shrink accordingly. (This behaviour can be
  276. changed in the prefrences.) Despite that not all the entries share the
  277. same fields you can fill in every field for every entry, by changing the
  278. entry type to a type that supports the field and then switch back to the
  279. original field. Although you can not see the field it will be saved with
  280. the entry.
  281.  
  282. Every field has a maximum of 2500 characters.
  283.  
  284. For every entry there are required and optional fields. The optional
  285. fields are not required by BibCard, but are required for BiBTeX to work.
  286. BiBTeX will warn you when you forgot the required fields. The optional
  287. fields are only used by BiBTeX if they have a value.
  288.  
  289. The only field that has to be filled in for BibCard is the CiteKey field.
  290.  
  291.  
  292. The window title shows the window number, the number of the current entry,
  293. the total entries and the name of the bib file.
  294.  
  295.  
  296. This window is also an AppWindow. This means that when you drop an icon
  297. on this window, the associated file will be loaded. This will only work if
  298. BibCard is opened on the Workbench screen.
  299.  
  300.  
  301.  
  302. Cite Window
  303. -----------
  304.  
  305. When the Cite Window is opened you get a list of all the CiteKeys in the
  306. bib file. When an entry is selected the Bib Window is updated, when you
  307. change the entry in the Bib Window in any way, the selection in the Cite
  308. Window will not change, except for the CiteKey.
  309.  
  310. The fields that are marked by the Find option are highlighted. That way
  311. you get a quick overview about the bib items that are matched.
  312.  
  313.  
  314. With the Cycle Gagdget you can select the fields that are shown in the
  315. ListView. There are 22 different fields so be patient when you want a
  316. particular field in the ListView. (CycleToMenu is recommended.)
  317.  
  318.  
  319.  
  320. Find Window
  321. -----------
  322.  
  323. In the Find panel you can enter a search expression. Every bib entry that
  324. matches the search criterium get tagged when you click the [FIND] button.
  325.  
  326. With the [NEXT] button you can display every next tagged item in the list.
  327. With the [PREV] button you can display every previous tagged item in the
  328. list.
  329.  
  330. The [UNTAG] button in the Find panel clears all tags.
  331.  
  332. By selecting the CheckBoxes, the checked fields are searched for the given
  333. search expression. The state of the CheckBoxes will be remembered between
  334. different calls.
  335.  
  336. For now it is not possible to edit the bib file while the Find panel is
  337. open. This will be changed in the future.
  338.  
  339. With the menu items `Find Next' and `Find Prev' you can go from tagged
  340. item to tagged item and also be able to edit the items.
  341.  
  342.  
  343. The following wildcards can be used to specify a pattern:
  344.  
  345.             Pattern Matches
  346.             ------- --------
  347.             ?       any single character
  348.             c*      zero or more occurrences of character c
  349.             c+      one or more occurrences of character c
  350.             \?      a question mark (?)
  351.             \*      an asterisk (*)
  352.             \+      a plus sign (+)
  353.  
  354.  
  355.  
  356. Annotation Window
  357. -----------------
  358.  
  359. For every BibFile opened there can be one Annotation Window open. You will
  360. get a TextField gadget where you can enter multiple lines. There is no
  361. filtering in the characters you enter. So if you enter three line feeds,
  362. there will also three line feeds saved in the *.bib file.
  363.  
  364.  
  365.  
  366. Abbrevation Window
  367. ------------------
  368.  
  369. The abbrevations could be edited here. See the LaTeX manual for the use of
  370. abbrevations. The entries should be in the form:
  371.  
  372.     jb = "Journal of Biology"
  373.  
  374. Thus: the abbrevation, a '=' character and then the full name surrounded by
  375. double quotes.
  376.  
  377. With the [New] button you add an item to the list and with the [Delete]
  378. button you can remove an item from the list. The abbrevatiosn appear in
  379. the bibfile as @string entries, one @string for each abbrevation.
  380.  
  381.  
  382.  
  383. Unknown Fields Window
  384. ---------------------
  385.  
  386. Every field that is unknown for BibCard is stored and saved. When
  387. you want to edit these fields you must use the Unknown Fields Window. With
  388. the [New] button you add an item to the list and with the [Delete] button
  389. you can remove an item from the list. The [Ok] button transfers everything
  390. to the current BibItem while the [Cancel] button leaves the BibItem
  391. unchanged.
  392.  
  393. The fields have the following format:
  394.  
  395.     remark = "This is a remark."
  396.  
  397.  
  398.  
  399. Preferences
  400. -----------
  401.  
  402.  * Field delimiters:
  403.  
  404.     The field delimiters can be set here.  When saving a bib file the
  405.     field strings will be surrounded with a pair of braces {} or a pair of
  406.     double quotes "".
  407.  
  408.     When you have a \" in your bib file, you must set the delimiters to
  409.     braces because when reading the bib file all entries after the \" will
  410.     be not read in.
  411.  
  412.     Default is ""
  413.  
  414.  
  415.  * Fixed window size:
  416.  
  417.     When this is set, the window size will not change between the
  418.     different entry types. This will speed up the change between different
  419.     entries.
  420.  
  421.     Default is off.
  422.  
  423.  * Save icon:
  424.  
  425.    When this option is selected, an icon will be saved with each bibfile.
  426.  
  427.  
  428.  * Font:
  429.  
  430.    The font for a custom screen can here be selected. All windows are font
  431.    sensitive, only when very large font sizes are being used some cosmetic
  432.    problems could occur.
  433.  
  434.  
  435.  * Screen type:
  436.  
  437.     The screen type tells where BibCard will open its window. There are
  438.     three possibilities:
  439.  
  440.         Default - Open on the default public screen.
  441.  
  442.         Custom  - Open a public screen for itself.
  443.  
  444.         Public  - Open on a named existing public screen
  445.  
  446.     When a custom screen is selected, a screen mode can be chosen with the
  447.     ListView Button gadget next to the Screen Mode text field. For this
  448.     option version 38 of the asl.library is required.
  449.  
  450.     When the last option is chosen, the name of the pubplic screen where
  451.     BibCard must open can be entered in the string gadget.
  452.  
  453.     Default for screen type is default public screen and for the custom
  454.     screen 'PAL:High Res' or 'NTSC:High Res' depending on the default
  455.     frequency.
  456.  
  457.  
  458. With [Save] the setting will be saved in the current directory in the file
  459. 'BibCard.prefs'. The [Use] button will use the settings without saving
  460. them.
  461.  
  462. When BibCard opens it looks first for the preference file in the current
  463. directory (where BibCard is started from) and the in the PROGDIR: (where
  464. BibCard resides).
  465.  
  466.  
  467. """"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
  468.  
  469.  
  470. 3. Help
  471. =======
  472.  
  473. Pressing Help in the main window gives some help about Help.
  474.  
  475. When the Help key is pressed inside a string gadget you get some
  476. information explaining the use of the field.
  477.  
  478. When selecting an entry type under the Entry menu and then pressing the
  479. Help key gives also some information about the entry type.
  480.  
  481. The Find Window gives also some help about the wildcards that can be used.
  482.  
  483. The Abbrevation Window gives help about the format of an abbrevation.
  484.  
  485. The Unknown Fields Window gives help about the format of an unknown field.
  486.  
  487.  
  488.  
  489. """"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
  490.  
  491.  
  492. 4. Future
  493. =========
  494.  
  495.  
  496. There are still things to do, but this version is usable for the average
  497. BiBTeX person. Things on the wish list are:
  498.  
  499.  - Locale support.
  500.  
  501.  - Set some more preferences (ideas?).
  502.  
  503.  - ARexx port.
  504.  
  505.  - AmigaGuide manual
  506.  
  507.  
  508.  
  509. """"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
  510.  
  511.  
  512. 5. Acknowledgements
  513. ===================
  514.  
  515.  
  516. The source for reading and saving the bib files comes from the 1.11
  517. distribution from BibCard for XWindows from The Department of Computer
  518. Science and Applied Mathematics of Berne, Switzerland, written by Bruno
  519. Grossniklaus.
  520. It is changed by me in some degree to suit the Amiga. (All XView calls
  521. are removed and the Reference structure is replaced by my own.)
  522.  
  523.  
  524. The textfield.gadget is Copyright © 1995 Mark Thomas and can be found on
  525. AmiNet.
  526.  
  527.  
  528.  
  529. """"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
  530.  
  531.  
  532. 6. History
  533. ==========
  534.  
  535.   v0.91 (27.8.95)
  536.   ---------------
  537.   
  538.     o During install under kickstart 2.0 the textfield.gadget ended up in
  539.       the wrong place.
  540.  
  541.     o When there was no field entry in a bibfile the field seperator ","
  542.       showed up in the fields in bibcard. Now the "," is removed and when
  543.       the bib file is saved these entries will be skipped.
  544.  
  545.     o The ListView in the Cite Window is now a MultipleSelect ListView.
  546.       The behaviour is the same as under u*ix.
  547.  
  548.     o ToolTypes are now supported.
  549.  
  550.     o The option to open on a named public screen was broken. Now it is
  551.       working again.
  552.  
  553.     o The BibFile window is now an AppWindow.
  554.     
  555.     o An icon can now be saved with the bibfile.
  556.  
  557.     o For every field 2500 characters can be entered (was 256).
  558.  
  559.  
  560.  
  561.   v0.9 (10.8.95)
  562.   -------------
  563.   
  564.     o The type of screen where bibcard opens can now be selected.
  565.     
  566.     o Font is selectable and all windows are now font senstive.
  567.     
  568.     o Added some more help.
  569.  
  570.     o Adding and deleting entries to the Abbrevation and Unknown Window
  571.       could result in a serious hangup.
  572.  
  573.     o Added PROGDIR: to the search path for the preference file.
  574.  
  575.     o Rewritten some parts of the doc.
  576.  
  577.  
  578.   v0.8 (18.7.95)
  579.   --------------
  580.  
  581.     o Preferences can now be saved.
  582.  
  583.     o Add [NEXT] and [PREV] buttons in the Find panel.
  584.  
  585.     o Added menu and key support to the Cite Window.
  586.  
  587.     o The Annotation field now uses the textfield.gadget. With this
  588.       external gadget you can enter multiple lines.
  589.  
  590.     o The Cite Window and the Annotation Window can now be open at the same
  591.       time and every BibFile has it's own Annotaton and Cite Window.
  592.  
  593.     o Unknown fields are now editable.
  594.  
  595.     o An interlace option is added for custom screens.
  596.  
  597.  
  598.  
  599.   v0.7 (11.6.95)
  600.   --------------
  601.  
  602.     o Added editting of unknown fields.
  603.  
  604.     o Added Cut/Copy/Paste functions using an internal buffer.
  605.  
  606.     o A line will be drawn between the required and the optional fields.
  607.  
  608.     o Field delimiters can be set between "" and {} pairs.
  609.     
  610.     o The main window can be set at fixed size.
  611.  
  612.     o Added Find option.
  613.  
  614.  
  615.   v0.6 (8.5.95)
  616.   --------------
  617.  
  618.     o Initial release
  619.